Skip to main content

Data Management and Migration

ThorAPI generated applications do not use data.sql, Liquibase, or generated migration scripts as the default schema-management path.

The generated schema lifecycle is deliberately narrow:

  • Hibernate auto-DDL creates and expands generated tables from the current ThorAPI/OpenAPI model.
  • ValkyrAI schema fixing adapts supported drift that Hibernate does not reliably repair, especially changed enum constraints and text columns that need to become long enough for generated models.
  • Flyway is allowed only as an optional customer migration tool. It is not enabled by default and it is not part of ThorAPI generated schemas.

What ThorAPI Owns​

ThorAPI owns the schema implied by the current OpenAPI contract and generated JPA entities. That means it can safely support additive and widening changes that keep generated code and database structures aligned.

ChangeDefault handling
New generated tableHibernate auto-DDL
New generated columnHibernate auto-DDL
Wider text columnValkyrAI schema fixing
Updated enum value constraintValkyrAI schema fixing
New generated relation column or join tableHibernate auto-DDL

This is the normal path for ValkyrAI and ThorAPI builds.

What ThorAPI Does Not Own​

ThorAPI does not attempt destructive or semantic data migrations. The generator should not remove production data, guess intent, or make irreversible changes because a model changed.

Out of scope for ThorAPI automated schema management:

  • Dropping tables
  • Dropping columns
  • Shrinking columns
  • Renaming tables
  • Renaming columns
  • Moving data between old and new structures
  • Rewriting customer-specific production data

Those operations require an explicit migration plan outside the generated schema lifecycle.

Why There Is No data.sql​

data.sql is not part of the ValkyrAI schema-management model. Boot-time SQL seed files make it too easy to hide environment-specific assumptions, accidentally mutate live schemas, or create a second schema authority beside generated JPA.

Use application bootstrap services, explicit test fixtures, or customer-owned Flyway migrations instead. Keep schema shape controlled by the generated model plus schema fixing.

Why Liquibase Is Not Used​

Liquibase is not used in ValkyrAI or ThorAPI generated schemas. Do not add Liquibase changelogs, generated Liquibase templates, Liquibase test fixtures, or Liquibase startup configuration.

If a deployment needs migration scripts, use the optional Flyway path below.

Optional Flyway Path​

Flyway is supported as a customer option, not as the default runtime path. According to Redgate Flyway documentation, migrations are version-controlled SQL scripts used to deploy consistent database changes across environments, and migrate applies pending migrations in order. See Flyway migrations.

Use Flyway when a customer needs a controlled data migration that ThorAPI should not automate.

Recommended production-grade workflow:

  1. Generate a clean schema from the updated ThorAPI build.
  2. Compare the old production schema to the clean generated schema.
  3. Write explicit Flyway migrations that move data from the old structure to the new structure.
  4. Rehearse the migration against a production-like copy.
  5. Cut over to the migrated schema once the generated code and target schema match.

Flyway baseline migrations can help new environments start from a cumulative schema state while existing environments continue through versioned migrations. See Flyway baseline migrations.

Example: Safe Generated Expansion​

OpenAPI contract:

components:
  schemas:
    ContentData:
      type: object
      properties:
        content:
          type: string
          maxLength: 500000
        status:
          type: string
          enum:
            - draft
            - published
            - archived

Generated JPA intent:

@Column(length = 500000)
private String content;

@Enumerated(EnumType.STRING)
private StatusEnum status;

Expected schema handling:

  • Hibernate creates the table and columns when the schema is new.
  • Schema fixing widens the text column when the existing column is too short.
  • Schema fixing adapts enum constraints when generated enum values change.
  • No data.sql file or migration changelog is needed.

Example: Customer-Owned Flyway Migration​

Use Flyway only for changes that require explicit data movement or destructive operations. For example, replacing customer.full_name with customer.first_name and customer.last_name is a semantic migration, not a ThorAPI auto-fix.

-- V20260602_01__split_customer_full_name.sql
ALTER TABLE customer ADD COLUMN first_name VARCHAR(255);
ALTER TABLE customer ADD COLUMN last_name VARCHAR(255);

UPDATE customer
SET
  first_name = CASE
    WHEN full_name IS NULL THEN NULL
    ELSE SUBSTRING_INDEX(full_name, ' ', 1)
  END,
  last_name = CASE
    WHEN full_name IS NULL OR LOCATE(' ', full_name) = 0 THEN NULL
    ELSE SUBSTRING(full_name, LOCATE(' ', full_name) + 1)
  END;

The later removal of full_name should happen only after the new generated code is deployed, the migration is validated, and operators confirm no rollback path still needs the old column.

Runtime Configuration​

Default ValkyrAI runtime configuration keeps Flyway disabled:

spring:
  jpa:
    hibernate:
      ddl-auto: update
  flyway:
    enabled: false

Customers who opt into Flyway must own migration script ordering, validation, database backups, rollback planning, and schema/code compatibility checks.